<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Managing replication directories and files</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
    <link rel="up" href="rep.html" title="Chapter 13.  Berkeley DB Replication" />
    <link rel="prev" href="rep_partview.html" title="Replication views" />
    <link rel="next" href="rep_mgrmulti.html" title="Running Replication Manager in multiple processes" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 12.1.6.2</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Managing replication directories and files</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="rep_partview.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 13.  Berkeley DB Replication </th>
          <td width="20%" align="right"> <a accesskey="n" href="rep_mgrmulti.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="rep_filename"></a>Managing replication directories and files</h2>
          </div>
        </div>
      </div>
      <div class="toc">
        <dl>
          <dt>
            <span class="sect2">
              <a href="rep_filename.html#rep_dir">Replication database directory
            considerations</a>
            </span>
          </dt>
          <dt>
            <span class="sect2">
              <a href="rep_filename.html#rep_files">Managing replication internal
            files</a>
            </span>
          </dt>
        </dl>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="rep_dir"></a>Replication database directory
            considerations</h3>
            </div>
          </div>
        </div>
        <p>
            If your application is going to locate databases in any
            directory other than the environment home directory, you
            need to consider the directory structure for all sites.
            There are several recommendations to make in this area. 
        </p>
        <p> 
            The use of absolute pathnames is strongly discouraged
            when replication is in use. Absolute pathnames will not
            work if there is more than one site on a single machine.
            Replication with absolute pathnames is unlikely to work
            across different machines unless great care is taken to
            make sure the entire path is exactly the same on every
            machine. 
        </p>
        <p>
            If the master uses a data directory, as specified via
            <a href="../api_reference/C/envadd_data_dir.html" class="olink">DB_ENV-&gt;add_data_dir()</a> or <a href="../api_reference/C/envset_create_dir.html" class="olink">DB_ENV-&gt;set_create_dir()</a>, it is
            recommended that you create the same directory structure
            on all client sites. When the same directory structure
            appears on a master and the client, replication creates
            the client databases in the same directory as the master
            regardless of the local client directory settings. If a
            master directory is missing on a client, replication
            decides where to create the client databases by using the
            client's local directory settings and the Berkeley DB file
            naming rules as described in <a class="xref" href="env_naming.html" title="File naming">File naming</a>. 
        </p>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="rep_files"></a>Managing replication internal
            files</h3>
            </div>
          </div>
        </div>
        <p> 
            Whether you use the Base API or the Replication
            Manager, replication creates a set of internal files that
            are normally stored on-disk in your environment home
            directory. These files contain metadata which is necessary
            for replication operations, and so you should never delete
            these files. 
        </p>
        <p>
            You can cause these files to not be stored on disk, but
            instead to be held entirely in-memory, by specifying the
            <a href="../api_reference/C/repconfig.html#config_DB_REP_CONF_INMEM" class="olink">DB_REP_CONF_INMEM</a> flag to the <a href="../api_reference/C/repconfig.html" class="olink">DB_ENV-&gt;rep_set_config()</a> method. Doing
            this can improve your application's data throughput by
            avoiding the disk I/O associated with these metadata
            files. However, in the event that your application is shut
            down, the contents of these files are lost. This results
            in some loss of functionality, including an increased
            chance that elections will fail, or that the wrong site
            will win an election. See the <a href="../api_reference/C/repconfig.html#config_DB_REP_CONF_INMEM" class="olink">DB_REP_CONF_INMEM</a> flag
            description for more information. 
        </p>
        <p>
            Note that turning on <a href="../api_reference/C/repconfig.html#config_DB_REP_CONF_INMEM" class="olink">DB_REP_CONF_INMEM</a> means that
            Replication Manager cannot store group membership changes
            persistently. This is because Replication Manager stores
            group membership information in an internal database,
            which is held in memory when <a href="../api_reference/C/repconfig.html#config_DB_REP_CONF_INMEM" class="olink">DB_REP_CONF_INMEM</a> is turned
            on. For this reason, if your Replication Manager
            application requires replication metadata to be stored in
            memory, then you must manually identify all the sites in
            your replication group using the
                <code class="literal">DB_LEGACY</code> site configuration
            attribute. Be aware that this configuration needs to be
            made permanent. (Normally, <code class="literal">DB_LEGACY</code> is
            used only on a temporary basis for the purpose of
            upgrading old Replication Manager applications.) 
        </p>
        <p> Do the following: 
        </p>
        <div class="orderedlist">
          <ol type="1">
            <li>
              <p> 
                    Shut down all the sites in your replication
                    group. 
                </p>
            </li>
            <li>
              <p> 
                    For every site in your replication group: 
                </p>
              <div class="orderedlist">
                <ol type="a">
                  <li>
                    <p>
                            Configure a <a href="../api_reference/C/db_site.html" class="olink">DB_SITE</a> handle for the
                            local site. Use <a href="../api_reference/C/dbsite_set_config.html" class="olink">DB_SITE-&gt;set_config()</a> to
                            indicate that this is a legacy site by
                            setting the <code class="literal">DB_LEGACY</code>
                            parameter. 
                        </p>
                  </li>
                  <li>
                    <p>
                            Configure a <a href="../api_reference/C/db_site.html" class="olink">DB_SITE</a> handle for
                            <span class="emphasis"><em>every other site</em></span>
                            in the replication group. Set the
                            <code class="literal">DB_LEGACY</code> parameter
                            for each of these handles. 
                        </p>
                    <p> 
                            Please pay careful attention to this
                            step. To repeat: a <a href="../api_reference/C/db_site.html" class="olink">DB_SITE</a> handle MUST be
                            configured for EVERY site in the
                            replication group. 
                        </p>
                  </li>
                </ol>
              </div>
            </li>
            <li>
              <p> 
                    Restart all the sites in the replication group.
                </p>
            </li>
          </ol>
        </div>
        <p>
            Alternatively, you can store persistent environment
            metadata files, including those required by replication,
            in a location other than your environment home directory.
            This is necessary if your environment home directory is on
            a device that is unstable, because the persistent metadata
            files cannot be lost or deleted. You do this using the
            <a href="../api_reference/C/envset_metadata_dir.html" class="olink">DB_ENV-&gt;set_metadata_dir()</a> method. 
        </p>
        <p> 
            Note that you must configure the handling of your
            environment metadata consistently across your entire
            replication group. That is, if you place your replication
            metadata in-memory on one site, then it must be placed
            in-memory on all the sites in the group. Similarly, if you
            place your replication metadata files in a non-standard
            directory location on one site, then they must be placed
            in the exact same directory location on all the sites in
            your group. 
        </p>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="rep_partview.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="rep.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="rep_mgrmulti.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Replication views </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Running Replication Manager in
        multiple processes</td>
        </tr>
      </table>
    </div>
  </body>
</html>
